Inside Macintosh: QuickDraw GX Objects /

Chapter 8 - Tag Objects / Using Tag Objects

Creating and Manipulating Tag Objects

This section describes how you can create and interact with tag objects as whole entities. To manipulate tag object properties, use the functions described in the section "Manipulating Tag Object Properties" beginning on page 8-9.

Creating and Deleting a Tag Object

QuickDraw GX provides the GXNewTag function to allow you to create a new tag object. When you create the tag object, you provide its contents and you specify its tag type. Once you have created the tag object, you can attach it to any QuickDraw GX object (except another tag object) by making a call such as GXSetShapeTags, GXSetInkTags, or GXSetColorProfileTags.

Except when it overrides its own functions (as during printing), QuickDraw GX does not access or use the internal structure of the tag object you create; its contents and function are entirely up to you. Nor does QuickDraw GX make any restrictions on the tag type designation you provide, except that it cannot be zero. QuickDraw GX does not make any use of tag type except to use it for retrieving and replacing tag objects according to your instructions.

To delete your application's reference to a tag object, call the GXDisposeTag function. Calling GXDisposeTag may or may not actually release the memory allocated for the object, depending on the object's owner count. The function decreases the owner count of the tag object by 1; if that brings the owner count to zero, the object is completely deleted and its memory released. See "Manipulating a Tag Object's Owner Count" on page 8-11. Owner counts and what it means to dispose of an object are described in general in the chapter "Introduction to Objects" in this book.

Listing 8-1 is a library function that takes an arbitrary amount of data, makes it into a tag object of a given tag type, and attaches it to a specified shape. The function uses the GXNewTag function to create the tag object, and the GXDisposeTag function to dispose of its reference to the tag object after attaching it to the shape.

Listing 8-1 Adding data to a shape as a tag object

void AddShapeUser(gxShape source, const void *data, 
                  long length, long type)
{
   gxTag tempItem;
   tempItem = GXNewTag(type, length, data);
   GXSetShapeTags(source, 0, 0, 0, 1, &tempItem);
   GXDisposeTag(tempItem);
}

The GXNewTag function is described on page 8-13. The GXDisposeTag function is described on page 8-14.

Copying, Comparing, and Cloning Tag Objects

You can use the GXCopyToTag function to copy the information from one tag object to another or to create a new copy of an existing tag object.

You can test if two references refer to the same tag object by simply testing the references for equality. You can also compare two different tag objects for equality with the GXEqualTag functions. For two tag objects to be equal, their tag types and contents must be identical, although their owner counts need not be.

Object copies created with the GXCopyToTag function are always equal, by the criteria of GXEqualTag, to the objects from which they were copied.

In certain circumstances, you may want to copy a reference to a tag object without actually copying the object. This is called cloning, and you can use the GXCloneTag function to clone a tag object. Functionally, GXCloneTag does nothing more than increase the owner count of the tag object. For more information about cloning objects, see the chapter "Introduction to Objects" in this book. For information on manipulating owner counts, see the section "Manipulating a Tag Object's Owner Count" on page 8-11.

The GXCopyToTag function is described on page 8-15. The GXEqualTag function is described on page 8-16. The GXCloneTag function is described on page 8-17.

Loading and Unloading Tag Objects

Although you rarely need to, you can influence memory-allocation decisions involving objects that you have created. If your application needs to have a tag object in memory, you can force QuickDraw GX to load the tag object into memory. When your application no longer needs the tag object in a loaded state, you can instruct QuickDraw GX to unload it.

You call the GXLoadTag function to make sure that a tag object is in memory; if necessary, QuickDraw GX brings the object into memory from an unloaded state. You can call the GXUnloadTag function to instruct QuickDraw GX that it is free to unload the tag object at any time. These functions are described in the memory management chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.